home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_groff.idb / usr / freeware / info / groff-2.z / groff-2
Text File  |  2002-04-08  |  51KB  |  1,533 lines
  1. This is groff, produced by makeinfo version 4.0 from groff.texinfo.
  2.  
  3. INFO-DIR-SECTION Miscellaneous
  4. START-INFO-DIR-ENTRY
  5. * Groff: (groff).  The GNU troff document formatting system.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This Info file documents GNU troff version 1.16.
  9.  
  10.    Published by the Free Software Foundation 59 Temple Place, Suite 330
  11. Boston, MA  02111-1307  USA
  12.  
  13.    Copyright (C) 1994-2000 Free Software Foundation, Inc.
  14.  
  15.    Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.  
  19.    Permission is granted to copy and distribute modified versions of
  20. this manual under the conditions for verbatim copying, provided that the
  21. entire resulting derived work is distributed under the terms of a
  22. permission notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that this permission notice may be stated in a
  27. translation approved by the Foundation.
  28.  
  29.    Permission is granted to copy and distribute modified versions of
  30. this manual under the conditions for verbatim copying, provided also
  31. that the section entitled "GNU General Public License" is included
  32. exactly as in the original, and provided that the entire resulting
  33. derived work is distributed under the terms of a permission notice
  34. identical to this one.
  35.  
  36.    Permission is granted to copy and distribute translations of this
  37. manual into another language, under the above conditions for modified
  38. versions, except that the section entitled "GNU General Public License"
  39. may be included in a translation approved by the Free Software
  40. Foundation instead of in the original English.
  41.  
  42. 
  43. File: groff,  Node: Basics,  Next: Common Features,  Prev: Tutorial for Macro Users,  Up: Tutorial for Macro Users
  44.  
  45. Basics
  46. ======
  47.  
  48.    This section covers some of the basic concepts necessary to
  49. understand how to use a macro package.(1) (*note Basics-Footnote-1::)
  50. References are made throughout to more detailed information, if desired.
  51.  
  52.    `gtroff' reads an input file prepared by the user and outputs a
  53. formatted document suitable for publication or framing.  The input
  54. consists of text, or words to be printed, and embedded commands
  55. ("requests" and "escapes"), which tell `gtroff' how to format the
  56. output.  For more detail on this, see *Note Embedded Commands::.
  57.  
  58.    The word "argument" is used in this chapter to mean a word or number
  59. which appears on the same line as a request, and which modifies the
  60. meaning of that request.  For example, the request
  61.  
  62.  
  63.      .sp
  64.  
  65. spaces one line, but
  66.  
  67.  
  68.      .sp 4
  69.  
  70. spaces four lines.  The number 4 is an argument to the `sp' request
  71. which says to space four lines instead of one.  Arguments are separated
  72. from the request and from each other by spaces (_no_ tabs).  More
  73. details on this can be found in *Note Request Arguments::.
  74.  
  75.    The primary function of `gtroff' is to collect words from input
  76. lines, fill output lines with those words, justify the right-hand margin
  77. by inserting extra spaces in the line, and output the result.  For
  78. example, the input:
  79.  
  80.  
  81.      Now is the time
  82.      for all good men
  83.      to come to the aid
  84.      of their party.
  85.      Four score and seven
  86.      years ago,...
  87.  
  88. is read, packed onto output lines, and justified to produce:
  89.  
  90.      Now is the time for all good men to come to the aid of their party.
  91.      Four score and seven years ago,...
  92.  
  93.    Sometimes a new output line should be started even though the current
  94. line is not yet full; for example, at the end of a paragraph.  To do
  95. this it is possible to cause a "break", which starts a new output line.
  96. Some requests cause a break automatically, as normally do blank input
  97. lines and input lines beginning with a space.
  98.  
  99.    Not all input lines are text to be formatted.  Some input lines are
  100. requests which describe how to format the text.  Requests always have a
  101. period (`.') or an apostrophe (`'') as the first character of the input
  102. line.
  103.  
  104.    The text formatter also does more complex things, such as
  105. automatically numbering pages, skipping over page boundaries, putting
  106. footnotes in the correct place, and so forth.
  107.  
  108.    Here are a few hints for preparing text for input to `gtroff'.
  109.  
  110.    * First, keep the input lines short.  Short input lines are easier to
  111.      edit, and `gtroff' packs words onto longer lines anyhow.
  112.  
  113.    * In keeping with this, it is helpful to begin a new line after every
  114.      comma or phrase, since common corrections are to add or delete
  115.      sentences or phrases.
  116.  
  117.    * End each sentence with two spaces - or better, start each sentence
  118.      on a new line.  `gtroff' recognizes characters that usually end a
  119.      sentence, and inserts sentence space accordingly.
  120.  
  121.    * Do not hyphenate words at the end of lines - `gtroff' is smart
  122.      enough to hyphenate words as needed, but is not smart enough to
  123.      take hyphens out and join a word back together.  Also, words such
  124.      as "mother-in-law" should not be broken over a line, since then a
  125.      space can occur where not wanted, such as "mother- in-law".
  126.  
  127.    `gtroff' double spaces output text automatically if you use the
  128. request `.ls 2'.  Reactivate single spaced mode by typing `.ls 1'.
  129.  
  130.    A number of requests allow to change the way the output looks,
  131. sometimes called the "layout" of the output page.  Most of these
  132. requests adjust the placing of "white space" (blank lines or spaces).
  133.  
  134.    The `.bp' request starts a new page, causing a line break.
  135.  
  136.    The request `.sp N' leaves N lines of blank space.  N can be omitted
  137. (meaning skip a single line) or can be of the form Ni (for N inches) or
  138. Nc (for N centimeters).  For example, the input:
  139.  
  140.  
  141.      .sp 1.5i
  142.      My thoughts on the subject
  143.      .sp
  144.  
  145. leaves one and a half inches of space, followed by the line "My
  146. thoughts on the subject", followed by a single blank line (more
  147. measurement units are available, see *Note Measurements::).
  148.  
  149.    Text lines can be centered by using the `ce' request.  The line
  150. after `ce' is centered (horizontally) on the page.  To center more than
  151. one line, use `.ce N' (where N is the number of lines to center),
  152. followed by the N lines.  To center many lines without counting them,
  153. type:
  154.  
  155.  
  156.      .ce 1000
  157.      lines to center
  158.      .ce 0
  159.  
  160. The `.ce 0' request tells `groff' to center zero more lines, in other
  161. words, stop centering.
  162.  
  163.    All of these requests cause a break; that is, they always start a new
  164. line.  To start a new line without performing any other action, use
  165. `br'.
  166.  
  167. 
  168. File: groff,  Node: Basics-Footnotes,  Up: Basics
  169.  
  170.    (1) This section is derived from `Writing Papers with nroff using
  171. -me' by Eric P. Allman.
  172.  
  173. 
  174. File: groff,  Node: Common Features,  Prev: Basics,  Up: Tutorial for Macro Users
  175.  
  176. Common Features
  177. ===============
  178.  
  179.    `gtroff' provides very low-level operations for formatting a
  180. document.  There are many common routine operations which are done in
  181. all documents.  These common operations are written into "macros" and
  182. collected into a "macro package".
  183.  
  184.    All macro packages provide certain common capabilities which fall
  185. into the following categories.
  186.  
  187. * Menu:
  188.  
  189. * Paragraphs::
  190. * Sections and Chapters::
  191. * Headers and Footers::
  192. * Page Layout Adjustment::
  193. * Displays::
  194. * Footnotes and Annotations::
  195. * Table of Contents::
  196. * Indices::
  197. * Paper Formats::
  198. * Multiple Columns::
  199. * Font and Size Changes::
  200. * Predefined Strings::
  201. * Preprocessor Support::
  202. * Configuration and Customization::
  203.  
  204. 
  205. File: groff,  Node: Paragraphs,  Next: Sections and Chapters,  Prev: Common Features,  Up: Common Features
  206.  
  207. Paragraphs
  208. ----------
  209.  
  210.    One of the most common and most used capability is starting a
  211. paragraph.  There are a number of different types of paragraphs, any of
  212. which can be initiated with macros supplied by the macro package.
  213. Normally, paragraphs start with a blank line and the first line
  214. indented, like the text in this manual.  There are also block style
  215. paragraphs, which omit the indentation:
  216.  
  217.  
  218.      Some   men  look   at  constitutions   with  sanctimonious
  219.      reverence, and deem them like the ark of the covenant, too
  220.      sacred to be touched.
  221.  
  222. And there are also indented paragraphs which begin with a tag or label
  223. at the margin and the remaining text indented.
  224.  
  225.      one   This is  the first paragraph.  Notice  how the first
  226.            line of  the resulting  paragraph lines up  with the
  227.            other lines in the paragraph.
  228.      longlabel
  229.            This  paragraph   had  a  long   label.   The  first
  230.            character of text on the first line does not line up
  231.            with  the  text  on  second  and  subsequent  lines,
  232.            although they line up with each other.
  233.  
  234.    A variation of this is a bulleted list.
  235.  
  236. 
  237. File: groff,  Node: Sections and Chapters,  Next: Headers and Footers,  Prev: Paragraphs,  Up: Common Features
  238.  
  239. Sections and Chapters
  240. ---------------------
  241.  
  242.    Most macro packages supply some form of section headers.  The
  243. simplest kind is simply the heading on a line by itself in bold type.
  244. Others supply automatically numbered section heading or different
  245. heading styles at different levels.  Some, more sophisticated, macro
  246. packages supply macros for starting chapters and appendices.
  247.  
  248. 
  249. File: groff,  Node: Headers and Footers,  Next: Page Layout Adjustment,  Prev: Sections and Chapters,  Up: Common Features
  250.  
  251. Headers and Footers
  252. -------------------
  253.  
  254.    Every macro package gives some way to manipulate the headers and
  255. footers (or "titles") on each page.  Some packages allow for different
  256. ones on the even and odd pages (for material printed in a book form).
  257.  
  258.    The titles are called three-part titles, that is, there is a
  259. left-justified part, a centered part, and a right-justified part.  An
  260. automatically generated page number may be put in any of these fields
  261. with the `%' character (see *Note Page Layout::, for more details).
  262.  
  263. 
  264. File: groff,  Node: Page Layout Adjustment,  Next: Displays,  Prev: Headers and Footers,  Up: Common Features
  265.  
  266. Page Layout
  267. -----------
  268.  
  269.    Most macro packages let the user specify top and bottom margins and
  270. other details about the appearance of the printed pages.
  271.  
  272. 
  273. File: groff,  Node: Displays,  Next: Footnotes and Annotations,  Prev: Page Layout Adjustment,  Up: Common Features
  274.  
  275. Displays
  276. --------
  277.  
  278.    Displays are sections of text to be set off from the body of the
  279. paper.  Major quotes, tables, and figures are types of displays, as are
  280. all the examples used in this document.
  281.  
  282.    "Major quotes" are quotes which are several lines long, and hence
  283. are set in from the rest of the text without quote marks around them.
  284.  
  285.    A "list" is an indented, single spaced, unfilled display.  Lists
  286. should be used when the material to be printed should not be filled and
  287. justified like normal text, such as columns of figures or the examples
  288. used in this paper.
  289.  
  290.    A "keep" is a display of lines which are kept on a single page if
  291. possible.  An example for a keep might be a diagram.  Keeps differ from
  292. lists in that lists may be broken over a page boundary whereas keeps are
  293. not.
  294.  
  295.    Floating keeps move relative to the text.  Hence, they are good for
  296. things which are referred to by name, such as "See figure 3".  A
  297. floating keep appears at the bottom of the current page if it fits;
  298. otherwise, it appears at the top of the next page.  Meanwhile, the
  299. surrounding text `flows' around the keep, thus leaving no blank areas.
  300.  
  301. 
  302. File: groff,  Node: Footnotes and Annotations,  Next: Table of Contents,  Prev: Displays,  Up: Common Features
  303.  
  304. Footnotes and Annotations
  305. -------------------------
  306.  
  307.    There are a number of requests to save text for later printing.
  308.  
  309.    "Footnotes" are printed at the bottom of the current page.
  310.  
  311.    "Delayed text" is very similar to a footnote except that it is
  312. printed when called for explicitly.  This allows a list of references to
  313. appear (for example) at the end of each chapter, as is the convention in
  314. some disciplines.
  315.  
  316.    Most macro packages which supply this functionality also supply a
  317. means of automatically numbering either type of annotation.
  318.  
  319. 
  320. File: groff,  Node: Table of Contents,  Next: Indices,  Prev: Footnotes and Annotations,  Up: Common Features
  321.  
  322. Table of Contents
  323. -----------------
  324.  
  325.    "Tables of contents" are a type of delayed text having a tag
  326. (usually the page number) attached to each entry after a row of dots.
  327. The table accumulates throughout the paper until printed, usually after
  328. the paper has ended.  Many macro packages provide the ability to have
  329. several tables of contents (e.g. a standard table of contents, a list
  330. of tables, etc).
  331.  
  332. 
  333. File: groff,  Node: Indices,  Next: Paper Formats,  Prev: Table of Contents,  Up: Common Features
  334.  
  335. Indices
  336. -------
  337.  
  338.    While some macro packages use the term "index", none actually
  339. provide that functionality.  The facilities they call indices are
  340. actually more appropriate for tables of contents.
  341.  
  342. 
  343. File: groff,  Node: Paper Formats,  Next: Multiple Columns,  Prev: Indices,  Up: Common Features
  344.  
  345. Paper Formats
  346. -------------
  347.  
  348.    Some macro packages provide stock formats for various kinds of
  349. documents.  Many of them provide a common format for the title and
  350. opening pages of a technical paper.  The `mm' macros in particular
  351. provide formats for letters and memoranda.
  352.  
  353. 
  354. File: groff,  Node: Multiple Columns,  Next: Font and Size Changes,  Prev: Paper Formats,  Up: Common Features
  355.  
  356. Multiple Columns
  357. ----------------
  358.  
  359.    Some macro packages (but not `man') provide the ability to have two
  360. or more columns on a page.
  361.  
  362. 
  363. File: groff,  Node: Font and Size Changes,  Next: Predefined Strings,  Prev: Multiple Columns,  Up: Common Features
  364.  
  365. Font and Size Changes
  366. ---------------------
  367.  
  368.    The built-in font and size functions are not always intuitive, so all
  369. macro packages provide macros to make these operations simpler.
  370.  
  371. 
  372. File: groff,  Node: Predefined Strings,  Next: Preprocessor Support,  Prev: Font and Size Changes,  Up: Common Features
  373.  
  374. Predefined Strings
  375. ------------------
  376.  
  377.    Most macro packages provide various predefined strings for a variety
  378. of uses; examples are sub- and superscripts, printable dates, quotes and
  379. various special characters.
  380.  
  381. 
  382. File: groff,  Node: Preprocessor Support,  Next: Configuration and Customization,  Prev: Predefined Strings,  Up: Common Features
  383.  
  384. Preprocessor Support
  385. --------------------
  386.  
  387.    All macro packages provide support for the various preprocessors and
  388. may extend their functionality.
  389.  
  390.    For example, all macro packages mark tables (which are processed with
  391. `gtbl') by placing them between `.TS' and `.TE' macros.  The `ms' macro
  392. package has an option, `.TSH', that prints a caption at the top of a
  393. new page (when the table is too long to fit on a single page).
  394.  
  395. 
  396. File: groff,  Node: Configuration and Customization,  Prev: Preprocessor Support,  Up: Common Features
  397.  
  398. Configuration and Customization
  399. -------------------------------
  400.  
  401.    Some macro packages provide means of customizing many of the details
  402. of how the package behaves.  This ranges from setting the default type
  403. size to changing the appearance of section headers.
  404.  
  405. 
  406. File: groff,  Node: Macro Packages,  Next: gtroff Reference,  Prev: Tutorial for Macro Users,  Up: Top
  407.  
  408. Macro Packages
  409. **************
  410.  
  411.    This chapter documents the main macro packages that come with
  412. `groff'.
  413.  
  414. * Menu:
  415.  
  416. * man::
  417. * mdoc::
  418. * ms::
  419. * me::
  420. * mm::
  421.  
  422. 
  423. File: groff,  Node: man,  Next: mdoc,  Prev: Macro Packages,  Up: Macro Packages
  424.  
  425. `man'
  426. =====
  427.  
  428.    This is the most popular and probably the most important macro
  429. package of `groff'.  It is easy to use, and a vast majority of manual
  430. pages are based on it.
  431.  
  432. * Menu:
  433.  
  434. * Man options::
  435. * Man usage::
  436. * Man font macros::
  437. * Miscellaneous man macros::
  438. * Predefined man strings::
  439. * Preprocessors in man pages::
  440.  
  441. 
  442. File: groff,  Node: Man options,  Next: Man usage,  Prev: man,  Up: man
  443.  
  444. Options
  445. -------
  446.  
  447.    The command line format for using the `man' macros with `groff' is:
  448.  
  449.  
  450.      groff -m man [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rPNNN ]
  451.            [ -rSXX ] [ -rXNNN ] [ FILES... ]
  452.  
  453. It is possible to use `-man' instead of `-m man'.
  454.  
  455. `-rcR=1'
  456.      This option (the default if a tty output device is used) creates a
  457.      single, very long page instead of multiple pages.  Use `-rcR=0' to
  458.      disable it.
  459.  
  460. `-rC1'
  461.      If more than one manual page is given on the command line, number
  462.      the pages continuously, rather than starting each at 1.
  463.  
  464. `-rD1'
  465.      Double-sided printing.  Footers for even and odd pages are
  466.      formatted differently.
  467.  
  468. `-rPNNN'
  469.      Page numbering starts with NNN rather than with 1.
  470.  
  471. `-rSXX'
  472.      Use XX (which can be 10, 11, or 12pt) as the base document font
  473.      size instead of the default value of 10pt.
  474.  
  475. `-rXNNN'
  476.      After page NNN, number pages as NNNa, NNNb, NNNc, etc.  For
  477.      example, the option `-rX2' produces the following page numbers: 1,
  478.      2, 2a, 2b, 2c, etc.
  479.  
  480. 
  481. File: groff,  Node: Man usage,  Next: Man font macros,  Prev: Man options,  Up: man
  482.  
  483. Usage
  484. -----
  485.  
  486.    This section describes the available macros for manual pages.  For
  487. further customization, put additional macros and requests into the file
  488. `man.local' which is loaded immediately after the `man' package.
  489.  
  490.  - Macro: .TH title section [extra1] [extra2] [extra3]
  491.      Set the title of the man page to TITLE and the section to SECTION,
  492.      which must have a value between 1 and 8.  The value of SECTION may
  493.      also have a string appended, e.g. `.pm', to indicate a specific
  494.      subsection of the man pages.
  495.  
  496.      Both TITLE and SECTION are positioned at the left and right in the
  497.      header line (with SECTION in parentheses immediately appended to
  498.      TITLE.  EXTRA1 is positioned in the middle of the footer line.
  499.      EXTRA2 is positioned at the left in the footer line (or at the
  500.      left on even pages and at the right on odd pages if double-sided
  501.      printing is active).  EXTRA3 is centered in the header line.
  502.  
  503.      For HTML output, headers and footers are completely suppressed.
  504.  
  505.      Additionally, this macro starts a new page; the new line number
  506.      is 1 again (except if the `-rC1' option is given on the command
  507.      line) - this feature is intended only for formatting multiple man
  508.      pages; a single man page should contain exactly one `TH' macro at
  509.      the beginning of the file.
  510.  
  511.  - Macro: .SH [heading]
  512.      Set up an unnumbered section heading sticking out to the left.
  513.      Prints out all the text following `SH' up to the end of the line
  514.      (or the text in the next line if there is no argument to `SH') in
  515.      bold face, one size larger than the base document size.
  516.      Additionally, the left margin for the following text is reset to
  517.      its default value.
  518.  
  519.  - Macro: .SS [heading]
  520.      Set up an unnumbered (sub)section heading.  Prints out all the text
  521.      following `SS' up to the end of the line (or the text in the next
  522.      line if there is no argument to `SS') in bold face, at the same
  523.      size as the base document size.  Additionally, the left margin for
  524.      the following text is reset to its default value.
  525.  
  526.  - Macro: .TP [nnn]
  527.      Set up an indented paragraph with label.  The indentation is set to
  528.      NNN if that argument is supplied (the default unit is `n' if
  529.      omitted), otherwise it is set to the default indentation value.
  530.  
  531.      The first line of text following this macro is interpreted as a
  532.      string to be printed flush-left, as it is appropriate for a label.
  533.      It is not interpreted as part of a paragraph, so there is no
  534.      attempt to fill the first line with text from the following input
  535.      lines.  Nevertheless, if the label is not as wide as the
  536.      indentation, then the paragraph starts at the same line (but
  537.      indented), continuing on the following lines.  If the label is
  538.      wider than the indentation, then the descriptive part of the
  539.      paragraph begins on the line following the label, entirely
  540.      indented.  Note that neither font shape nor font size of the label
  541.      is set to a default value; on the other hand, the rest of the text
  542.      has default font settings.
  543.  
  544.  - Macro: .LP
  545.  - Macro: .PP
  546.  - Macro: .P
  547.      These macros are mutual aliases.  Any of them causes a line break
  548.      at the current position, followed by a vertical space downwards by
  549.      the amount specified by the `PD' macro.  The font size and shape
  550.      are reset to the default value (10pt roman).  Finally, the current
  551.      left margin is restored.
  552.  
  553.  - Macro: .IP [designator] [nnn]
  554.      Set up an indented paragraph, using DESIGNATOR as a tag to mark
  555.      its beginning.  The indentation is set to NNN if that argument is
  556.      supplied (default unit is `n'), otherwise the default indentation
  557.      value is used.  Font size and face of the paragraph (but not the
  558.      designator) are reset to their default values.  To start an
  559.      indented paragraph with a particular indentation but without a
  560.      designator, use `""' (two double quotes) as the first argument of
  561.      `IP'.
  562.  
  563.      For example, to start a paragraph with bullets as the designator
  564.      and 4en indentation, write
  565.  
  566.  
  567.           .IP \(bu 4
  568.  
  569.  
  570.  - Macro: .HP [nnn]
  571.      Set up a paragraph with hanging left indentation.  The indentation
  572.      is set to NNN if that argument is supplied (default unit is `n'),
  573.      otherwise the default indentation value is used.  Font size and
  574.      face are reset to their default values.
  575.  
  576.  - Macro: .RS [nnn]
  577.      Move the left margin to the right by the value NNN if specified
  578.      (default unit is `n'); otherwise the default indentation value is
  579.      used.  Calls to the `RS' macro can be nested.
  580.  
  581.  - Macro: .RE [nnn]
  582.      Move the left margin back to level NNN; if no argument is given,
  583.      it moves one level back.  The first level (i.e., no call to `RS'
  584.      yet) has number 1, and each call to `RS' increases the level by 1.
  585.  
  586.    To summarize, the following macros cause a line break with the
  587. insertion of vertical space (which amount can be changed with the `PD'
  588. macro): `SH', `SS', `TP', `LP' (`PP', `P'), `IP', and `HP'.
  589.  
  590.    The macros `RS' and `RE' also cause a break but do not insert
  591. vertical space.
  592.  
  593. 
  594. File: groff,  Node: Man font macros,  Next: Miscellaneous man macros,  Prev: Man usage,  Up: man
  595.  
  596. Macros to set fonts
  597. -------------------
  598.  
  599.    The standard font is roman; the default text size is 10 point.
  600.  
  601.  - Macro: .SM [text]
  602.      Set the text on the same line or the text on the next line in a
  603.      font that is one point size smaller than the default font.
  604.  
  605.  - Macro: .SB [text]
  606.      Set the text on the same line or the text on the next line in
  607.      boldface font, one point size smaller than the default font.
  608.  
  609.  - Macro: .BI text
  610.      Set its arguments alternately in bold face and italic.  Thus,
  611.  
  612.  
  613.           .BI this "word and" that
  614.  
  615.      would set "this" and "that" in bold face, and "word and" in
  616.      italics.
  617.  
  618.  - Macro: .IB text
  619.      Set its arguments alternately in italic and bold face.
  620.  
  621.  - Macro: .RI text
  622.      Set its arguments alternately in roman and italic.
  623.  
  624.  - Macro: .IR text
  625.      Set its arguments alternately in italic and roman.
  626.  
  627.  - Macro: .BR text
  628.      Set its arguments alternately in bold face and roman.
  629.  
  630.  - Macro: .RB text
  631.      Set its arguments alternately in roman and bold face.
  632.  
  633.  - Macro: .R [text]
  634.      Set TEXT in roman font.  If no text is present on the line where
  635.      the macro is called, then the text of the next line appears in
  636.      roman.  This is the default font to which text is returned at the
  637.      end of processing of the other macros.
  638.  
  639.  - Macro: .B [text]
  640.      Set TEXT in bold face.  If no text is present on the line where
  641.      the macro is called, then the text of the next line appears in bold
  642.      face.
  643.  
  644.  - Macro: .I [text]
  645.      Set TEXT in italic.  If no text is present on the line where the
  646.      macro is called, then the text of the next line appears in italic.
  647.  
  648. 
  649. File: groff,  Node: Miscellaneous man macros,  Next: Predefined man strings,  Prev: Man font macros,  Up: man
  650.  
  651. Miscellaneous macros
  652. --------------------
  653.  
  654.    The default indentation is 7.2n for all output devices except for
  655. `grohtml' which ignores indentation.
  656.  
  657.  - Macro: .DT
  658.      Set tabs every 0.5 inches.  Since this macro is always called
  659.      during a `TH' request, it makes sense to call it only if the tab
  660.      positions have been changed.
  661.  
  662.  - Macro: .PD [nnn]
  663.      Adjust the empty space before a new paragraph (or section).  The
  664.      optional argument gives the amount of space (default unit is `v');
  665.      without parameter, the value is reset to its default value (1 line
  666.      for tty devices, 0.4v otherwise).
  667.  
  668.    This affects the macros `SH', `SS', `TP', `LP' (as well as `PP' and
  669. `P'), `IP', and `HP'.
  670.  
  671. 
  672. File: groff,  Node: Predefined man strings,  Next: Preprocessors in man pages,  Prev: Miscellaneous man macros,  Up: man
  673.  
  674. Predefined strings
  675. ------------------
  676.  
  677.    The following strings are defined:
  678.  
  679.  - String: *S
  680.      Switch back to the default font size.
  681.  
  682.  - String: *R
  683.      The `registered' sign.
  684.  
  685.  - String: Tm
  686.      The `trademark' sign.
  687.  
  688.  - String: lq
  689.  - String: rq
  690.      Left and right quote.  This is equal to `\(lq' and `\(rq',
  691.      respectively.
  692.  
  693. 
  694. File: groff,  Node: Preprocessors in man pages,  Prev: Predefined man strings,  Up: man
  695.  
  696. Preprocessors in `man' pages
  697. ----------------------------
  698.  
  699.    If a preprocessor like `gtbl' or `geqn' is needed, it has become
  700. common usage to make the first line of the man page look like this:
  701.  
  702.  
  703.      .\" WORD
  704.  
  705. Note the single space character after the double quote.  WORD consists
  706. of letters for the needed preprocessors: `e' for `geqn', `r' for
  707. `grefer', `t' for `gtbl'.  Modern implementations of the `man' program
  708. read this first line and automatically call the right preprocessor(s).
  709.  
  710. 
  711. File: groff,  Node: mdoc,  Next: ms,  Prev: man,  Up: Macro Packages
  712.  
  713. `mdoc'
  714. ======
  715.  
  716. 
  717. File: groff,  Node: ms,  Next: me,  Prev: mdoc,  Up: Macro Packages
  718.  
  719. `ms'
  720. ====
  721.  
  722. 
  723. File: groff,  Node: me,  Next: mm,  Prev: ms,  Up: Macro Packages
  724.  
  725. `me'
  726. ====
  727.  
  728. 
  729. File: groff,  Node: mm,  Prev: me,  Up: Macro Packages
  730.  
  731. `mm'
  732. ====
  733.  
  734. 
  735. File: groff,  Node: gtroff Reference,  Next: Preprocessors,  Prev: Macro Packages,  Up: Top
  736.  
  737. `gtroff' Reference
  738. ******************
  739.  
  740.    This chapter covers *all* of the facilities of `gtroff'.  Users of
  741. macro packages may skip it if not interested in details.
  742.  
  743. * Menu:
  744.  
  745. * Text::
  746. * Input Conventions::
  747. * Measurements::
  748. * Expressions::
  749. * Identifiers::
  750. * Embedded Commands::
  751. * Registers::
  752. * Manipulating Filling and Adjusting::
  753. * Manipulating Hyphenation::
  754. * Manipulating Spacing::
  755. * Tabs and Fields::
  756. * Character Translations::
  757. * Troff and Nroff Mode::
  758. * Line Layout::
  759. * Page Layout::
  760. * Page Control::
  761. * Fonts::
  762. * Sizes::
  763. * Strings::
  764. * Conditionals and Loops::
  765. * Writing Macros::
  766. * Page Motions::
  767. * Drawing Requests::
  768. * Traps::
  769. * Diversions::
  770. * Environments::
  771. * Suppressing output::
  772. * I/O::
  773. * Postprocessor Access::
  774. * Miscellaneous::
  775. * Gtroff Internals::
  776. * Debugging::
  777. * Implementation Differences::
  778. * Summary::
  779.  
  780. 
  781. File: groff,  Node: Text,  Next: Input Conventions,  Prev: gtroff Reference,  Up: gtroff Reference
  782.  
  783. Text
  784. ====
  785.  
  786.    `gtroff' input files contain text with control commands interspersed
  787. throughout.  But, even without control codes, `gtroff' still does
  788. several things with the input text:
  789.  
  790.    * filling and adjusting
  791.  
  792.    * adding additional space after sentences
  793.  
  794.    * hyphenating
  795.  
  796.    * inserting implicit line breaks
  797.  
  798. * Menu:
  799.  
  800. * Filling and Adjusting::
  801. * Hyphenation::
  802. * Sentences::
  803. * Tab Stops::
  804. * Implicit Line Breaks::
  805.  
  806. 
  807. File: groff,  Node: Filling and Adjusting,  Next: Hyphenation,  Prev: Text,  Up: Text
  808.  
  809. Filling and Adjusting
  810. ---------------------
  811.  
  812.    When `gtroff' reads text, it collects words from the input and fits
  813. as many of them together on one output line as it can.  This is known as
  814. "filling".
  815.  
  816.    Once `gtroff' has a "filled" line, it tries to "adjust" it.  This
  817. means it widens the spacing between words until the text reaches the
  818. right margin (in the default adjustment mode).  Extra spaces between
  819. words are preserved, but spaces at the end of lines are ignored.
  820. Spaces at the front of a line cause a "break" (breaks are explained in
  821. *Note Implicit Line Breaks::)
  822.  
  823.    *Note Manipulating Filling and Adjusting::.
  824.  
  825. 
  826. File: groff,  Node: Hyphenation,  Next: Sentences,  Prev: Filling and Adjusting,  Up: Text
  827.  
  828. Hyphenation
  829. -----------
  830.  
  831.    Since the odds are not great for finding a set of words, for every
  832. output line, which fit nicely on a line without inserting excessive
  833. amounts of space between words, `gtroff' hyphenates words so that it
  834. can justify lines without inserting too much space between words.  It
  835. uses an internal hyphenation algorithm (a simplified version of the
  836. algorithm used within TeX) to indicate which words can be hyphenated
  837. and how to do so.  When a word is hyphenated, the first part of the
  838. word is added to the current filled line being output (with an attached
  839. hyphen), and the other portion is added to the next line to be filled.
  840.  
  841.    *Note Manipulating Hyphenation::.
  842.  
  843. 
  844. File: groff,  Node: Sentences,  Next: Tab Stops,  Prev: Hyphenation,  Up: Text
  845.  
  846. Sentences
  847. ---------
  848.  
  849.    Although it is often debated, some typesetting rules say there
  850. should be different amounts of space after various punctuation marks.
  851. For example, the `Chicago typsetting manual' says that a period at the
  852. end of a sentence should have twice as much space following it as would
  853. a comma or a period as part of an abbreviation.
  854.  
  855.    `gtroff' does this by flagging certain characters (normally `!',
  856. `?', and `.') as "end of sentence" characters.  When `gtroff'
  857. encounters one of these characters at the end of a line, it appends a
  858. normal space followed by a "sentence space" in the formatted output.
  859. (This justifies one of the conventions mentioned in *Note Input
  860. Conventions::.)
  861.  
  862.    In addition, the following characters or glyphs are treated
  863. transparently while handling end of sentence characters: `"', `'', `)',
  864. `]', `*', `dg', and `rq'.
  865.  
  866.    See the `cflags' request in *Note Using Symbols::, for more details.
  867.  
  868.    To prevent the insertion of extra space after an end of sentence
  869. character (at the end of a line), append `\&'.
  870.  
  871. 
  872. File: groff,  Node: Tab Stops,  Next: Implicit Line Breaks,  Prev: Sentences,  Up: Text
  873.  
  874. Tab Stops
  875. ---------
  876.  
  877.    `gtroff' translates "tabulator characters", also called "tabs"
  878. (normally code point ASCII `0x09' or EBCDIC `0x05'), in the input into
  879. movements to the next tabulator stop.  These tab stops are initially
  880. located every half inch across the page.  Using this, simple tables can
  881. be made easily.  However, it can often be deceptive as the appearance
  882. (and width) of the text on a terminal and the results from `gtroff' can
  883. vary greatly.
  884.  
  885.    Also, a possible sticking point is that lines beginning with tab
  886. characters are still filled, again producing unexpected results.  For
  887. example, the following input
  888.  
  889.            1          2          3
  890.                       4          5
  891.  
  892. produces
  893.  
  894.            1          2          3                     4          5
  895.  
  896.    *Note Tabs and Fields::.
  897.  
  898. 
  899. File: groff,  Node: Implicit Line Breaks,  Prev: Tab Stops,  Up: Text
  900.  
  901. Implicit Line Breaks
  902. --------------------
  903.  
  904.    An important concept in `gtroff' is the "break".  When a break
  905. occurs, `gtroff' outputs the partially filled line (unjustified), and
  906. resumes collecting and filling text on the next output line.
  907.  
  908.    There are several ways to cause a break in `gtroff'.  A blank line
  909. not only causes a break, but it also outputs a one line vertical space
  910. (effectively a blank line).  Note that this behaviour can be modified
  911. with the blank line macro request `blm'.
  912.  
  913.    A line that begins with a space causes a break and the space is
  914. output at the beginning of the next line.  Note that this space isn't
  915. adjusted, even in fill mode.
  916.  
  917.    The end of file also causes a break - otherwise the last line of the
  918. document may vanish!
  919.  
  920.    Certain requests also cause breaks, implicitly or explicitly.  This
  921. is discussed in *Note Manipulating Filling and Adjusting::.
  922.  
  923. 
  924. File: groff,  Node: Input Conventions,  Next: Measurements,  Prev: Text,  Up: gtroff Reference
  925.  
  926. Input Conventions
  927. =================
  928.  
  929.    Since `gtroff' does filling automatically, it is traditional in
  930. `groff' not to try and type things in as nicely formatted paragraphs.
  931. These are some conventions commonly used when typing `gtroff' text:
  932.  
  933.    * Break lines after punctuation, particularly at the end of a
  934.      sentence and in other logical places.  Keep separate phrases on
  935.      lines by themselves, as entire phrases are often added or deleted
  936.      when editing.
  937.  
  938.    * Try to keep lines less than 40-60 characters, to allow space for
  939.      inserting more text.
  940.  
  941.    * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
  942.      try using spaces to get proper indentation).
  943.  
  944. 
  945. File: groff,  Node: Measurements,  Next: Expressions,  Prev: Input Conventions,  Up: gtroff Reference
  946.  
  947. Measurements
  948. ============
  949.  
  950.    `gtroff' (like many other programs) requires numeric parameters to
  951. specify various measurements.  Most numeric parameters(1) (*note
  952. Measurements-Footnote-1::) may have a "measurement unit" attached.
  953. These units are specified as a single character which immediately
  954. follows the number or expression.  Each of these units are understood,
  955. by `gtroff', to be a multiple of its "basic unit".  So, whenever a
  956. different measurement unit is specified `gtroff' converts this into its
  957. "basic units".  This basic unit, represented by a `u', is a device
  958. dependent measurement which is quite small, ranging from 1/75th to
  959. 1/72000th of an inch.  The values may be given as fractional numbers;
  960. however, fractional basic units are always rounded to integers.
  961.  
  962.    Some of the measurement units are completely independent of any of
  963. the current settings (e.g. type size) of `gtroff'.
  964.  
  965. `i'
  966.      Inches.  An antiquated measurement unit still in use in certain
  967.      backwards countries with incredibly low-cost computer equipment.
  968.      One inch is equal to 2.54cm.
  969.  
  970. `c'
  971.      Centimeters.  One centimeter is equal to 0.3937in.
  972.  
  973. `p'
  974.      Points.  This is a typesetter's measurement used for measure type
  975.      size.  It is 72 points to an inch.
  976.  
  977. `P'
  978.      Pica.  Another typesetting measurement.  6 Picas to an inch (and
  979.      12 points to a pica).
  980.  
  981. `s'
  982. `z'
  983.      *Note Fractional Type Sizes::, for a discussion of these units.
  984.  
  985.    The other measurements understood by `gtroff' depend on settings
  986. currently in effect in `gtroff'.  These are very useful for specifying
  987. measurements which should look proper with any size of text.
  988.  
  989. `m'
  990.      Ems.  This unit is equal to the current font size in points.  So
  991.      called because it is _approximately_ the width of the letter `m'
  992.      in the current font.
  993.  
  994. `n'
  995.      Ens.  This is half of an em.
  996.  
  997. `v'
  998.      Vertical space.  This is equivalent to the current line spacing.
  999.      *Note Sizes::, for more information about this.
  1000.  
  1001. `M'
  1002.      100ths of an em.
  1003.  
  1004. * Menu:
  1005.  
  1006. * Default Units::
  1007.  
  1008. 
  1009. File: groff,  Node: Measurements-Footnotes,  Up: Measurements
  1010.  
  1011.    (1) those that specify vertical or horizontal motion or a type size
  1012.  
  1013. 
  1014. File: groff,  Node: Default Units,  Prev: Measurements,  Up: Measurements
  1015.  
  1016. Default Units
  1017. -------------
  1018.  
  1019.    Many requests take a default unit.  While this can be helpful at
  1020. times, it can cause strange errors in some expressions.  For example,
  1021. the line length request expects em units.  Here are several attempts to
  1022. get a line length of 3.5 inches and their results:
  1023.  
  1024.  
  1025.      3.5i      =>   3.5i
  1026.      7/2       =>   0i
  1027.      7/2i      =>   0i
  1028.      7i/2      =>   0.1i
  1029.      7i/2u     =>   3.5i
  1030.  
  1031. Everything is converted to basic units first.  In the above example it
  1032. is assumed that 1i equals 240u, and 1m equals 10p (thus 1m equals 33u).
  1033. The value 7i/2 is first handled as 7i/2m, then converted to 1680u/66u
  1034. which is 25u, and this is approximately 0.1i.
  1035.  
  1036.    Thus, the safest way to specify measurements is to always attach a
  1037. scaling indicator.  If you want to multiply or divide by a certain
  1038. scalar value, use `u' as the unit for that value.
  1039.  
  1040. 
  1041. File: groff,  Node: Expressions,  Next: Identifiers,  Prev: Measurements,  Up: gtroff Reference
  1042.  
  1043. Expressions
  1044. ===========
  1045.  
  1046.    `gtroff' has most arithmetic operators common to other languages:
  1047.  
  1048.    * Arithmetic: `+' (addition), `-' (subtraction), `/' (division), `*'
  1049.      (multiplication), `%' (modulo).
  1050.  
  1051.      `gtroff' only provides integer arithmetic.  The internal type used
  1052.      for computing results is `int', which is usually a 32bit signed
  1053.      integer.
  1054.  
  1055.    * Comparison: `<' (less than), `>' (greater than), `<=' (less than
  1056.      or equal), `>=' (greater than or equal), `=' (equal), `==' (the
  1057.      same as `=').
  1058.  
  1059.    * Logical: `&' (logical and), `:' (logical or).
  1060.  
  1061.    * Unary operators: `-' (negating, i.e. changing the sign), `+' (just
  1062.      for completeness; does nothing in expressions), `!' (logical not;
  1063.      this works only within `if' and `while' requests).  See below for
  1064.      the use of unary operators in motion requests.
  1065.  
  1066.    * Extrema: `>?' (maximum), `<?' (minimum).  For example, `5>?3'
  1067.      yields `5'.
  1068.  
  1069.    * Scaling: `(C;E)'.  Evaluate E using C as the default scaling
  1070.      indicator.  If C is missing, ignore scaling indicators in the
  1071.      evaluation of E.
  1072.  
  1073.    Parentheses may be used as in any other language.  However, in
  1074. `gtroff' they are necessary to ensure order of evaluation.  `gtroff'
  1075. has no operator precedence; expressions are evaluated left to right.
  1076. This means that `gtroff' evaluates `3+5*4' as if it were parenthesized
  1077. like `(3+5)*4', not as `3+(5*4)', as might be expected.
  1078.  
  1079.    For many requests which cause a motion on the page, the unary
  1080. operators work differently.  The `+' and `-' operators then indicate a
  1081. motion relative to the current position (down or up, respectively), and
  1082. the `|' operator indicates an absolute position on the page or input
  1083. line.  `+' and `-' are also treated differently by the following
  1084. requests and escapes: `bp', `in', `ll', `lt', `nm', `nr', `pl', `pn',
  1085. `po', `ps', `rt', `ti', `\R', and `\s'.  Here the plus and minus signs
  1086. indicate increments and decrements.
  1087.  
  1088.    *Note Setting Registers::.
  1089.  
  1090.    Due to the way arguments are parsed, spaces are not allowed in
  1091. expressions, unless the entire expression is surrounded by parentheses.
  1092.  
  1093.    *Note Request Arguments::, and *Note Conditionals and Loops::.
  1094.  
  1095. 
  1096. File: groff,  Node: Identifiers,  Next: Embedded Commands,  Prev: Expressions,  Up: gtroff Reference
  1097.  
  1098. Identifiers
  1099. ===========
  1100.  
  1101.    Like any other language, `gtroff' has rules for properly formed
  1102. "identifiers".  In `gtroff', an identifier can be made up of almost any
  1103. printable character, with the exception of the following characters:
  1104.  
  1105.    * Whitespace characters (spaces, tabs, and newlines).
  1106.  
  1107.    * Backspace (ASCII `0x08' or EBCDIC `0x16') and character code
  1108.      `0x01'.
  1109.  
  1110.    * The following input characters are invalid and are ignored if
  1111.      `groff' runs on a machine based on ASCII, causing a warning
  1112.      message of type `input' (see *Note Debugging::, for more details):
  1113.      `0x00', `0x0B', `0x0D'-`0x1F', `0x80'-`0x9F'.
  1114.  
  1115.      And here are the invalid input characters if `groff' runs on an
  1116.      EBCDIC host: `0x00', `0x08', `0x09', `0x0B', `0x0D'-`0x14',
  1117.      `0x17'-`0x1F', `0x30'-`0x3F'.
  1118.  
  1119.      Currently, some of these reserved codepoints are used internally,
  1120.      thus making it non-trivial to extend `gtroff' to cover Unicode or
  1121.      other character sets and encodings which use characters of these
  1122.      ranges.
  1123.  
  1124.      Note that invalid characters are removed before parsing; an
  1125.      identifier `foo', followed by an invalid character, followed by
  1126.      `bar' is treated as `foobar'.
  1127.  
  1128.    For example, any of the following is valid.
  1129.  
  1130.  
  1131.      br
  1132.      PP
  1133.      (l
  1134.      end-list
  1135.      @_
  1136.  
  1137. Note that identifiers longer than two characters with a closing bracket
  1138. (`]') in its name can't be accessed with escape sequences which expect
  1139. an identifier as a parameter.  For example, `\[foo]]' accesses the
  1140. glyph `foo', followed by `]', whereas `\C'foo]'' really asks for glyph
  1141. `foo]'.
  1142.  
  1143.  - Escape: \A'IDENT'
  1144.      Test whether an identifier IDENT is valid in `gtroff'.  It expands
  1145.      to the character 1 or 0 according to whether its argument (usually
  1146.      delimited by quotes) is or is not acceptable as the name of a
  1147.      string, macro, diversion, number register, environment, or font.
  1148.      It returns 0 if no argument is given.  This is useful for looking
  1149.      up user input in some sort of associative table.
  1150.  
  1151.  
  1152.           \A'end-list'
  1153.               => 1
  1154.  
  1155.  
  1156.    *Note Escapes::, for details on parameter delimiting characters.
  1157.  
  1158.    Identifiers in `gtroff' can be any length, but, in some contexts,
  1159. `gtroff' needs to be told where identifiers end and text begins (and in
  1160. different ways depending on their length):
  1161.  
  1162.    * Single character.
  1163.  
  1164.    * Two characters.  Must be prefixed with `(' in some situations.
  1165.  
  1166.    * Arbitrary length (`gtroff' only).  Must be bracketed with `['
  1167.      and `]' in some situations.  Any length identifier can be put in
  1168.      brackets.
  1169.  
  1170.    Unlike many other programming languages, undefined identifiers are
  1171. silently ignored or expanded to nothing.  When `gtroff' finds an
  1172. undefined identifier, it emits a warning then:
  1173.  
  1174.    * If the identifier is a string, macro, or diversion, `gtroff'
  1175.      defines it as empty.
  1176.  
  1177.    * If the identifier is a number register, `gtroff' defines it with a
  1178.      value of 0.
  1179.  
  1180.    *Note Warnings::.
  1181.  
  1182.    *Note Interpolating Registers::, and *Note Strings::.
  1183.  
  1184. 
  1185. File: groff,  Node: Embedded Commands,  Next: Registers,  Prev: Identifiers,  Up: gtroff Reference
  1186.  
  1187. Embedded Commands
  1188. =================
  1189.  
  1190.    Most documents need more functionality beyond filling, adjusting and
  1191. implicit line breaking.  In order to gain further functionality,
  1192. `gtroff' allows commands to be embedded into the text, in two ways.
  1193.  
  1194.    The first is a "request" which takes up an entire line, and does
  1195. some large-scale operation (e.g. break lines, start new pages).
  1196.  
  1197.    The other is an "escape" which can be embedded anywhere in the text,
  1198. or even as an argument to a request.  Escapes generally do more minor
  1199. operations like sub- and superscripts, print a symbol, etc.
  1200.  
  1201. * Menu:
  1202.  
  1203. * Requests::
  1204. * Macros::
  1205. * Escapes::
  1206.  
  1207. 
  1208. File: groff,  Node: Requests,  Next: Macros,  Prev: Embedded Commands,  Up: Embedded Commands
  1209.  
  1210. Requests
  1211. --------
  1212.  
  1213.    A request line begins with a control character, which is either a
  1214. single quote (`'', the "no-break control character") or a period (`.',
  1215. the normal "control character").  These can be changed; see *Note
  1216. Character Translations::, for details.  After this there may be
  1217. optional tabs or spaces followed by an identifier which is the name of
  1218. the request.  This may be followed by any number of space-separated
  1219. arguments (_no_ tabs here).
  1220.  
  1221.    Since a control character followed by whitespace only is ignored, it
  1222. is common practice to use this feature for structuring the source code
  1223. of documents or macro packages.
  1224.  
  1225.  
  1226.      .de foo
  1227.      .  tm This is foo.
  1228.      ..
  1229.      .
  1230.      .
  1231.      .de bar
  1232.      .  tm This is bar.
  1233.      ..
  1234.  
  1235.    Another possibility is to use the blank line macro request `blm' by
  1236. assigning an empty macro to it.
  1237.  
  1238.  
  1239.      .de do-nothing
  1240.      ..
  1241.      .blm do-nothing  \" activate blank line macro
  1242.      
  1243.      .de foo
  1244.      .  tm This is foo.
  1245.      ..
  1246.      
  1247.      
  1248.      .de bar
  1249.      .  tm This is bar.
  1250.      ..
  1251.      
  1252.      .blm             \" deactivate blank line macro
  1253.  
  1254.    To begin a line with a control character without it being
  1255. interpreted, precede it with `\&'.  This represents a zero width space,
  1256. which means it does not affect the output.
  1257.  
  1258.    In most cases the period is used as a control character.  Several
  1259. requests cause a break implicitly; using the single quote control
  1260. character prevents this.
  1261.  
  1262. * Menu:
  1263.  
  1264. * Request Arguments::
  1265.  
  1266. 
  1267. File: groff,  Node: Request Arguments,  Prev: Requests,  Up: Requests
  1268.  
  1269. Request Arguments
  1270. .................
  1271.  
  1272.    Arguments to requests (and macros) are processed much like the shell:
  1273. The line is split into arguments according to spaces.  An argument
  1274. which is intended to contain spaces can either be enclosed in double
  1275. quotes, or have the spaces "escaped" with backslashes.
  1276.  
  1277.    Here are a few examples:
  1278.  
  1279.  
  1280.      .uh The Mouse Problem
  1281.      .uh "The Mouse Problem"
  1282.      .uh The\ Mouse\ Problem
  1283.  
  1284. The first line is the `uh' macro being called with 3 arguments, `The',
  1285. `Mouse', and `Problem'.  The latter two have the same effect of calling
  1286. the `uh' macro with one argument, `The Mouse Problem'.(1) (*note
  1287. Request Arguments-Footnote-1::)
  1288.  
  1289.    A double quote which isn't preceded by a space doesn't start a macro
  1290. argument.  If not closing a string, it is printed literally.
  1291.  
  1292.    For example,
  1293.  
  1294.  
  1295.      .xxx a" "b c" "de"fg"
  1296.  
  1297. has the arguments `a"', `b c', `de', and `fg"'.
  1298.  
  1299.    Duoble quotes in the `ds' request are handled differently.  *Note
  1300. Strings::, for more details.
  1301.  
  1302. 
  1303. File: groff,  Node: Request Arguments-Footnotes,  Up: Request Arguments
  1304.  
  1305.    (1) The last solution, i.e., using escaped spaces, is "classical" in
  1306. the sense that it can be found in most `troff' documents.
  1307. Nevertheless, it is not optimal in all situations, since `\ ' inserts a
  1308. fixed-width, non-breaking space character which can't stretch.
  1309. `gtroff' provides a different command `\~' to insert a stretchable,
  1310. non-breaking space.
  1311.  
  1312. 
  1313. File: groff,  Node: Macros,  Next: Escapes,  Prev: Requests,  Up: Embedded Commands
  1314.  
  1315. Macros
  1316. ------
  1317.  
  1318.    `gtroff' has a "macro" facility for defining a series of lines which
  1319. can be invoked by name.  They are called in the same manner as requests
  1320. - arguments also may be passed in the same manner.
  1321.  
  1322.    *Note Writing Macros::, and *Note Request Arguments::.
  1323.  
  1324. 
  1325. File: groff,  Node: Escapes,  Prev: Macros,  Up: Embedded Commands
  1326.  
  1327. Escapes
  1328. -------
  1329.  
  1330.    Escapes may occur anywhere in the input to `gtroff'.  They usually
  1331. begin with a backslash and are followed by a single character which
  1332. indicates the function to be performed.  The escape character can be
  1333. changed; see *Note Character Translations::.
  1334.  
  1335.    Escape sequences which require an identifier as a parameter accept
  1336. three possible syntax forms.
  1337.  
  1338.    * The next single character is the identifier.
  1339.  
  1340.    * If this single character is an opening parenthesis, take the
  1341.      following two characters as the identifier.  Note that there is no
  1342.      closing parenthesis after the identifier.
  1343.  
  1344.    * If this single character is an opening bracket, take all characters
  1345.      until a closing bracket as the identifier.
  1346.  
  1347. Examples:
  1348.  
  1349.  
  1350.      \fB
  1351.      \n(XX
  1352.      \*[TeX]
  1353.  
  1354.    Other escapes may require several arguments and/or some special
  1355. format.  In such cases the argument is traditionally enclosed in single
  1356. quotes (and quotes are always used in this manual for the definitions
  1357. of escape sequences).  The enclosed text is then processed according to
  1358. what that escape expects.  Example:
  1359.  
  1360.  
  1361.      \l'1.5i\(bu'
  1362.  
  1363.    Note that the quote character can be replaced with any other
  1364. character which does not occur in the argument (even a newline or a
  1365. space character) in the following escapes: `\o', `\b', and `\X'.  This
  1366. makes e.g.
  1367.  
  1368.  
  1369.      A caf
  1370.      \o
  1371.      e\'
  1372.      
  1373.      
  1374.      in Paris
  1375.        => A cafe' in Paris
  1376.  
  1377. possible, but it is better not to use this feature to avoid confusion.
  1378.  
  1379.    The following escapes sequences (which are handled similarly to
  1380. characters since they don't take a parameter) are also allowed as
  1381. delimiters: `\%', `\ ', `\|', `\^', `\{', `\}', `\'', `\`', `\-', `\_',
  1382. `\!', `\?', `\@', `\)', `\/', `\,', `\&', `\~', `\0', `\a', `\c', `\d',
  1383. `\e', `\E', `\p', `\r', `\t', and `\u'.  Again, don't use these if
  1384. possible.
  1385.  
  1386.    No newline characters as delimiters are allowed in the following
  1387. escapes: `\A', `\Z', `\C', and `\w'.
  1388.  
  1389.    Finally, the escapes `\D', `\h', `\H', `\l', `\L', `\N', `\R', `\s',
  1390. `\S', `\v', and `\x' can't use the following characters as delimiters:
  1391.  
  1392.    * The digits `0'-`9'.
  1393.  
  1394.    * The (single-character) operators `+-/*%<>=&:().'.
  1395.  
  1396.    * The space, tab, and newline characters.
  1397.  
  1398.    * All escape sequences except `\%', `\{', `\}', `\'', `\`', `\-',
  1399.      `\_', `\!', `\@', `\/', `\c', `\e', and `\p'.
  1400.  
  1401.    To have a backslash (actually, the current escape character) appear
  1402. in the output several escapes are defined: `\\', `\e' or `\E'.  These
  1403. are very similar, and only differ with respect to being used in macros
  1404. or diversions.  *Note Copy-in Mode::, and *Note Diversions::, for more
  1405. information.
  1406.  
  1407.    *Note Identifiers::, and *Note Character Translations::.
  1408.  
  1409. * Menu:
  1410.  
  1411. * Comments::
  1412.  
  1413. 
  1414. File: groff,  Node: Comments,  Prev: Escapes,  Up: Escapes
  1415.  
  1416. Comments
  1417. ........
  1418.  
  1419.    Probably one of the most(1) (*note Comments-Footnote-1::) common
  1420. forms of escapes is the comment.
  1421.  
  1422.  - Escape: \"
  1423.      Start a comment.  Everything to the end of the input line is
  1424.      ignored.
  1425.  
  1426.      This may sound simple, but it can be tricky to keep the comments
  1427.      from interfering with the appearance of the final output.
  1428.  
  1429.      If the escape is to the right of some text or a request, that
  1430.      portion of the line is ignored, but the space leading up to it is
  1431.      noticed by `gtroff'.  This only affects the `.ds' and `.as'
  1432.      request.
  1433.  
  1434.      One possibly irritating idiosyncracy is that tabs must not be used
  1435.      to line up comments.  Tabs are not treated as white space between
  1436.      the request and macro arguments.
  1437.  
  1438.      A comment on a line by itself is treated as a blank line, because
  1439.      after eliminating the comment, that is all that remains:
  1440.  
  1441.  
  1442.           Test
  1443.           \" comment
  1444.           Test
  1445.  
  1446.      produces
  1447.  
  1448.  
  1449.           Test
  1450.           
  1451.           Test
  1452.  
  1453.      To avoid this, it is common to start the line with `.\"' which
  1454.      causes the line to be treated as an undefined request and thus
  1455.      ignored completely.
  1456.  
  1457.      Another commenting scheme seen sometimes is three consecutive
  1458.      single quotes (`'''') at the beginning of a line.  This works, but
  1459.      `gtroff' gives a warning about an undefined macro (namely `'''),
  1460.      which is harmless, but irritating.
  1461.  
  1462.  - Escape: \#
  1463.      To avoid all this, `gtroff' has a new comment mechanism using the
  1464.      `\#' escape.  This escape works the same as `\"' except that the
  1465.      newline is also ignored:
  1466.  
  1467.  
  1468.           Test
  1469.           \# comment
  1470.           Test
  1471.  
  1472.      produces
  1473.  
  1474.  
  1475.           Test Test
  1476.  
  1477.      as expected.
  1478.  
  1479.  - Request: .ig yy
  1480.      Ignore all input until `gtroff' encounters the macro named `.'YY
  1481.      on a line by itself (or `..' if YY is not specified).  This is
  1482.      useful for commenting out large blocks of text:
  1483.  
  1484.  
  1485.           text text text...
  1486.           .ig
  1487.           This is part of a large block
  1488.           of text that has been
  1489.           temporarily(?) commented out.
  1490.           
  1491.           We can restore it simply by removing
  1492.           the .ig request and the ".." at the
  1493.           end of the block.
  1494.           ..
  1495.           More text text text...
  1496.  
  1497.      produces
  1498.  
  1499.  
  1500.           text text text...  More text text text...
  1501.  
  1502.      Note that the commented-out block of text does not cause a break.
  1503.  
  1504.      The input is read in copy-mode; auto-incremented registers _are_
  1505.      affected (*note Auto-increment::).
  1506.  
  1507. 
  1508. File: groff,  Node: Comments-Footnotes,  Up: Comments
  1509.  
  1510.    (1) Unfortunately, this is a lie.  But hopefully future `gtroff'
  1511. hackers will believe it `:-)'
  1512.  
  1513. 
  1514. File: groff,  Node: Registers,  Next: Manipulating Filling and Adjusting,  Prev: Embedded Commands,  Up: gtroff Reference
  1515.  
  1516. Registers
  1517. =========
  1518.  
  1519.    Numeric variables in `gtroff' are called "registers".  There are a
  1520. number of built-in registers, supplying anything from the date to
  1521. details of formatting parameters.
  1522.  
  1523.    *Note Identifiers::, for details on register identifiers.
  1524.  
  1525. * Menu:
  1526.  
  1527. * Setting Registers::
  1528. * Interpolating Registers::
  1529. * Auto-increment::
  1530. * Assigning Formats::
  1531. * Built-in Registers::
  1532.  
  1533.